home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / reaction_lib.doc < prev    next >
Encoding:
Text File  |  1999-10-29  |  17.7 KB  |  534 lines
  1. TABLE OF CONTENTS
  2.  
  3. reaction.lib/--datasheet--
  4. reaction.lib/BrowserNodesA
  5. reaction.lib/ChooserLabelsA
  6. reaction.lib/ClickTabsA
  7. reaction.lib/FreeBrowserNodes
  8. reaction.lib/FreeChooserLabels
  9. reaction.lib/FreeRadioButtons
  10. reaction.lib/GetAttrs
  11. reaction.lib/GetCode
  12. reaction.lib/LBAddNodeA
  13. reaction.lib/LBEditNodeA
  14. reaction.lib/LBRemNode
  15. reaction.lib/LibDoGadgetMethodA
  16. reaction.lib/OpenLayoutWindowTagList
  17. reaction.lib/RadioButtonsA
  18. reaction.lib/GetCode
  19. reaction.lib/FreeClickTabs
  20. reaction.lib/--datasheet--                         reaction.lib/--datasheet--
  21.  
  22.    NAME
  23.        reaction.lib -- ReAction support functions link library
  24.  
  25.    DESCRIPTION
  26.        This library contains the autoinitialization code for the shared
  27.        library versions of the ReAction BOOPSI classes, thus sparing the
  28.        programmer from having to OpenLibrary() the classes manually. It
  29.        also contains stub functions for the node taglist allocation
  30.        functions of certain classes. These can be used by the DICE
  31.        compiler, which does not support #pragma tagcall.
  32.  
  33.        Autoinitialization works just like normal SAS/C library autoinit.
  34.        By declaring the class base extern in all source files (easiest
  35.        done by #including the "proto" header, such as proto/layout.h),
  36.        the SAS/C linker will take the class base, together with the code
  37.        to open the class on program startup (and to close it on exit)
  38.        from this library. The same autoinitialisation code should also
  39.        work for DICE.
  40.  
  41.        The version number to use for OpenLibrary() is contained in the
  42.        variable long __reactionversion. If you do not set this global
  43.        variable in your source code, it will be linked from this library,
  44.        With the release of V41 or greater classes in Release 2.0, it has
  45.        been considered prudent to requier them, so you should set this
  46.        value to 41. Note however, that classes NOT part of the ReAction
  47.        package are not effected by __reactionversion and will open with
  48.        any version available.
  49.  
  50.        If the opening of a class fails, the autoinit code will cause the
  51.        program to exit with an error message of "Can't open version Y of
  52.        X". If you wish to continue without using a certain class, you
  53.        will have to open it manually.
  54.  
  55.    SUPPORTED CLASSES
  56.        Version 1 of reaction.lib supports the following ReAction classes.
  57.        The version variable of each class is listed after the shared class
  58.        name.
  59.  
  60.        images/bevel.image
  61.        images/bitmap.image
  62.        gadgets/button.gadget
  63.        gadgets/checkbox.gadget
  64.        gadgets/chooser.gadget
  65.        gadgets/datebrowser.gadget
  66.        images/drawlist.image
  67.        gadgets/fuelgauge.gadget
  68.        gadgets/getfile.gadget
  69.        gadgets/getfont.gadget
  70.        gadgets/getscreenmode.gadget
  71.        images/glyph.image
  72.        gadgets/integer.gadget
  73.        images/label.image
  74.        gadgets/layout.gadget
  75.        gadgets/listbrowser.gadget
  76.        gadgets/radiobutton.gadget
  77.        gadgets/scroller.gadget
  78.        gadgets/slider.gadget
  79.        gadgets/space.gadget
  80.        gadgets/speedbar.gadget
  81.        gadgets/string.gadget
  82.  
  83.        Additionally, to help programmers, reaction.lib contains
  84.        autoinitialization for the following shared classes NOT part of
  85.        the ReAction package. Please remember that these gadgets do not
  86.        necessarily contain a CLASS_GetClass() type function for getting
  87.        the base class. Some of them have registered class names, some
  88.        have a function with another name. Some don't have functions at
  89.        all, in which case special care must be taken to make sure the
  90.        autoinit code is loaded (reference the class base variable, for
  91.        example TapeDeckBase, somewhere within the source). Refer to the
  92.        documentation of these classes to find out more.
  93.  
  94.        gadgets/calendar.gadget
  95.        gadgets/colorwheel.gadget
  96.        gadgets/gradientslider.gadget
  97.        images/led.image
  98.        gadgets/statusbar.gadget
  99.        gadgets/tabs.gadget
  100.        gadgets/tapedeck.gadget
  101.        gadgets/textfield.gadget
  102.  
  103.    EXAMPLE
  104.        The following program will print out the class base of
  105.        layout.gadget and the base address of gradientslider.gadget (which
  106.        doesn't have functions or a proto header) when compiled and linked
  107.        with reaction.lib:
  108.  
  109.        #include <proto/layout.h>
  110.        #include <proto/dos.h>
  111.  
  112.        extern void *GradientSliderBase;
  113.        long __reactionversion = 37;
  114.  
  115.        main()
  116.        {
  117.            Printf( "layout.gadget minimum version %ld class base is %lx\n",
  118.                    __layoutversion, LAYOUT_GetClass() );
  119.            Printf( "explicit reference to GradientSliderBase will force "
  120.                    "initialization:\n base address is %lx\n",
  121.                    GradientSliderBase );
  122.        }
  123. reaction.lib/BrowserNodesA                         reaction.lib/BrowserNodesA
  124.  
  125.    NAME
  126.        BrowserNodesA -- Make a linked list of listbrowser nodes
  127.        BrowserNodes -- varags stub for BrowserNodesA
  128.  
  129.    SYNOPSIS
  130.        list = BrowserNodesA( array )
  131.        list = BrowserNodes( label, ... )
  132.        struct List *BrowserNodesA( STRPTR * )
  133.        struct List *BrowserNodes( STRPTR, ... )
  134.  
  135.    FUNCTION
  136.        Make a linked list of single column listbrowser nodes from the
  137.        NULL terminated label array. The labels are not copied, so they
  138.        must stay valid until the list is free'd.
  139.  
  140.    INPUTS
  141.        array -- a NULL terminated array of string pointers.
  142.  
  143.    RESULTS
  144.        list -- a linked list of chooser nodes
  145. reaction.lib/ChooserLabelsA                       reaction.lib/ChooserLabelsA
  146.  
  147.    NAME
  148.        ChooserLabelsA -- Make a linked list of chooser labels
  149.        ChooserLabels -- varags stub for ChooserLabelsA
  150.  
  151.    SYNOPSIS
  152.        list = ChooserLabelsA( array )
  153.        list = ChooserLabels( label, ... )
  154.        struct List *ChooserLabelsA( STRPTR * )
  155.        struct List *ChooserLabels( STRPTR, ... )
  156.  
  157.    FUNCTION
  158.        Make a linked list of chooser nodes from the NULL terminated
  159.        label array. The labels are not copied, so they must stay
  160.        valid until the list is free'd.
  161.  
  162.    INPUTS
  163.        array -- a NULL terminated array of string pointers.
  164.  
  165.    RESULTS
  166.        list -- a linked list of chooser nodes
  167. reaction.lib/ClickTabsA                               reaction.lib/ClickTabsA
  168.  
  169.    NAME
  170.        ClickTabsA -- Make a linked list of clicktab nodes
  171.        ClickTabs -- varags stub for ClickTabsA
  172.  
  173.    SYNOPSIS
  174.        list = ClickTabsA( array )
  175.        list = ClickTabs( label, ... )
  176.        struct List *ClickTabsA( STRPTR * )
  177.        struct List *ClickTabs( STRPTR, ... )
  178.  
  179.    FUNCTION
  180.        Make a linked list of clicktab nodes from the NULL terminated
  181.        label array. The labels are not copied, so they must stay
  182.        valid until the list is free'd.
  183.  
  184.    INPUTS
  185.        array -- a NULL terminated array of string pointers.
  186.  
  187.    RESULTS
  188.        list -- a linked list of clicktab nodes
  189. reaction.lib/FreeBrowserNodes                   reaction.lib/FreeBrowserNodes
  190.  
  191.    NAME
  192.        FreeBrowserNodes -- Free a linked list of chooser labels
  193.  
  194.    SYNOPSIS
  195.        FreeBrowserNodes( list )
  196.        void FreeBrowserNodes( struct List * )
  197.  
  198.    FUNCTION
  199.        Free a linked list of chooser labels allocated with
  200.        BrowserNodesA().
  201.  
  202.    INPUTS
  203.        list -- the list to free
  204.  
  205.    RESULTS
  206.        None
  207. reaction.lib/FreeChooserLabels                 reaction.lib/FreeChooserLabels
  208.  
  209.    NAME
  210.        FreeChooserLabels -- Free a linked list of chooser labels
  211.  
  212.    SYNOPSIS
  213.        FreeChooserLabels( list )
  214.        void FreeChooserLabels( struct List * )
  215.  
  216.    FUNCTION
  217.        Free a linked list of chooser labels allocated with
  218.        ChooserLabelsA().
  219.  
  220.    INPUTS
  221.        list -- the list to free
  222.  
  223.    RESULTS
  224.        None
  225. reaction.lib/FreeClickTabs                 reaction.lib/FreeClickTabs
  226.  
  227.    NAME
  228.        FreeClickTabs -- Free a linked list of chooser labels
  229.  
  230.    SYNOPSIS
  231.        FreeClickTabs( list )
  232.        void FreeClickTabs( struct List * )
  233.  
  234.    FUNCTION
  235.        Free a linked list of chooser labels allocated with
  236.        ClickTabsA().
  237.  
  238.    INPUTS
  239.        list -- the list to free
  240.  
  241.    RESULTS
  242.        None
  243. reaction.lib/FreeRadioButtons                   reaction.lib/FreeRadioButtons
  244.  
  245.    NAME
  246.        FreeRadioButtons -- Free a linked list of radiobuttons
  247.  
  248.    SYNOPSIS
  249.        FreeRadioButtons( list )
  250.        void FreeRadioButtons( struct List * )
  251.  
  252.    FUNCTION
  253.        Free a linked list of radiobuttons allocated with
  254.        RadioButtonsA().
  255.  
  256.    INPUTS
  257.        list -- the list to free
  258.  
  259.    RESULTS
  260.        None
  261. reaction.lib/GetAttrs                                   reaction.lib/GetAttrs
  262.  
  263.    NAME
  264.        GetAttrsA -- Get multiple object attributes
  265.        GetAttrs -- Varargs stub to GetAttrsA
  266.  
  267.    SYNOPSIS
  268.        count = GetAttrsA( object, taglist )
  269.  
  270.        count = GetAttrs( object, tag, address, ... )
  271.  
  272.        ULONG GetAttrsA( Object *, struct TagItem * )
  273.  
  274.        ULONG GetAttrs( Object *, Tag, ... )
  275.  
  276.    FUNCTION
  277.        Gets multiple attributes of an object iin a single call.
  278.        Remember that while the function returns the number of
  279.        attributes that were getable, it can not inform WHICH
  280.        attributes, if any, were not. Thus, you shouldn't use this
  281.        function when you are not sure that an attribute is getable.
  282.  
  283.    INPUTS
  284.        object - pointer to the object that should be queried
  285.        taglist - a list of tag and ULONG address pairs to fill
  286.  
  287.    RESULTS
  288.        The number of attributes that succeeded.
  289. reaction.lib/GetCode                                     reaction.lib/GetCode
  290.  
  291.    NAME
  292.        GetCode -- return the true IDCMP message code
  293.  
  294.    SYNOPSIS
  295.        code = GetCode( imsg )
  296.  
  297.        UWORD GetCode( struct IntuiMessage * )
  298.  
  299.    FUNCTION
  300.        Returns the true IntuiMessage code field. Layout.gadget replaces
  301.        the IDCMP_GADGETUP message with an IDCMP_IDCMPUPDATE. This function
  302.        will return the "gadgetup code" from the IDCMPUPDATE taglist if it
  303.        is found there, and otherwise the normal imsg->Code.
  304.  
  305.    INPUTS
  306.        imsg -- a pointer to an IntuiMessage
  307.  
  308.    RESULTS
  309.        The message's code field
  310. reaction.lib/LBAddNodeA                               reaction.lib/LBAddNodeA
  311.  
  312.    NAME
  313.        LBAddNodeA -- V41 listbrowser.gadget LBM_ADDNODE method stub
  314.        LBAddNode -- Varargs version of LBAddNodeA
  315.  
  316.    SYNOPSIS
  317.        node = LBAddNodeA( gadget, window, requester, node, tags )
  318.  
  319.        struct Node *LBAddNodeA( struct Gadget *, struct Window *,
  320.            struct Requester *, struct Node *, struct TagItem * );
  321.  
  322.        node = LBAddNode( gadget, window, requester, node, tag, ... )
  323.  
  324.        struct Node *LBAddNode( struct Gadget *, sruct Window *,
  325.            struct Requester *, struct Node *, ULONG, ... );
  326.  
  327.    FUNCTION
  328.        A function stub for calling LibDoGadgetMethodA() to allocate
  329.        and add a new node to a listbrowser list. The main advantage
  330.        of this function is to let you inline the vararg LBNA taglist.
  331.  
  332.    INPUTS
  333.        gadget = listbrowser object
  334.        window = the window in which the gadget is, or NULL
  335.        requester = the requester of the window, or NULL
  336.        node = the node before which to add the new node. NULL for
  337.            beginning of the list
  338.        tags = the LBNA node allocation taglist
  339.  
  340.    RESULT
  341.        A pointer to the newly allocated node, or NULL on failure.
  342.  
  343.    NOTES
  344.        This function uses the LibDoGadgetMethodA() function also
  345.        defined in this link library.
  346.  
  347.    SEE ALSO
  348.        LibDoGadgetMethodA()
  349. reaction.lib/LBEditNodeA                             reaction.lib/LBEditNodeA
  350.  
  351.    NAME
  352.        LBEditNodeA -- V41 listbrowser.gadget LBM_EDITNODE method stub
  353.        LBEditNode -- Varargs version of LBEditNodeA
  354.  
  355.    SYNOPSIS
  356.        success = LBEditNodeA( gadget, window, requester, node, tags )
  357.  
  358.        ULONG LBEditNodeA( struct Gadget *, struct Window *,
  359.            struct Requester *, struct Node *, struct TagItem * );
  360.  
  361.        success = LBEditNode( gadget, window, requester, node, tag, ... )
  362.  
  363.        ULONG LBEditNode( struct Gadget *, sruct Window *,
  364.            struct Requester *, struct Node *, ULONG, ... );
  365.  
  366.    FUNCTION
  367.        A function stub for calling LibDoGadgetMethodA() to modify an
  368.        existing node on a listbrowser list. The main advantage
  369.        of this function is to let you inline the vararg LBNA taglist.
  370.  
  371.    INPUTS
  372.        gadget = listbrowser object
  373.        window = the window in which the gadget is, or NULL
  374.        requester = the requester of the window, or NULL
  375.        node = the node to modify
  376.        tags = the LBNA node modification taglist
  377.  
  378.    RESULT
  379.        Nonzero on success.
  380.  
  381.    NOTES
  382.        This function uses the LibDoGadgetMethodA() function also
  383.        defined in this link library.
  384.  
  385.    SEE ALSO
  386.        LibDoGadgetMethodA()
  387. reaction.lib/LBRemNode                                 reaction.lib/LBRemNode
  388.  
  389.    NAME
  390.        LBRemNode -- V41 listbrowser.gadget LBM_REMNODE method stub
  391.  
  392.    SYNOPSIS
  393.        node = LBRemNode( gadget, window, requester, node )
  394.  
  395.        ULONG LBRemNode( struct Gadget *, struct Window *,
  396.            struct Requester *, struct Node * );
  397.  
  398.    FUNCTION
  399.        A function stub for calling LibDoGadgetMethodA() to remove and
  400.        free a node from a listbrowser list. This function mostly
  401.        exists for completeness's sake.
  402.  
  403.    INPUTS
  404.        gadget = listbrowser object
  405.        window = the window in which the gadget is, or NULL
  406.        requester = the requester of the window, or NULL
  407.        node = the node to free
  408.  
  409.    RESULT
  410.        Nonzero on success.
  411.  
  412.    NOTES
  413.        This function uses the LibDoGadgetMethodA() function also
  414.        defined in this link library.
  415.  
  416.    SEE ALSO
  417.        LibDoGadgetMethodA()
  418. reaction.lib/LibDoGadgetMethodA               reaction.lib/LibDoGadgetMethodA
  419.  
  420.    NAME
  421.        LibDoGadgetMethodA -- DoGadgetMethodA for V37 machines
  422.        LibDoGadgetMethod -- Varargs stub for LibDoGadgetMethodA
  423.  
  424.    SYNOPSIS
  425.        result = LibDoGadgetMethodA( Gadget, Window, Requester, Message )
  426.        D0                  A0      A1      A2         A3
  427.  
  428.        ULONG LibDoGadgetMethodA( struct Gadget *, struct Window *,
  429.            struct Requester *, Msg );
  430.  
  431.        result = LibDoGadgetMethod( Gadget, Window, Requester, MethodID, ...)
  432.  
  433.        ULONG LibDoGadgetMethod( struct Gadget *, struct Window *,
  434.            struct Requester *, ULONG, ... );
  435.  
  436.  
  437.    FUNCTION
  438.        Same as the DoGadgetMethod() function of intuition.library V39,
  439.        this function invokes a BOOPSI method and provides context
  440.        information for classes which implement custom Intuition gadgets.
  441.  
  442.        You should use this function for boopsi gadget objects,
  443.        or for "models" which propagate information to gadgets.
  444.  
  445.        Unlike DoMethod(), this function provides a GadgetInfo pointer
  446.        (if possible) when invoking the method.  Some classes may
  447.        require or benefit from this.
  448.  
  449.        On a V39 machine, this function calls the Intuition function.
  450.  
  451.    INPUTS
  452.        Gadget = abstract pointer to a boopsi gadget
  453.        Window = window gadget has been added to using AddGList() or AddGadget()
  454.        Requester = for REQGADGETs, requester containing the gadget
  455.        Msg = the boopsi message to send
  456.  
  457.    RESULT
  458.        The object does whatever it wants with the message you sent,
  459.        which might include updating its gadget visuals.
  460.  
  461.        The return value is defined per-method.
  462.  
  463.    NOTES
  464.        This function invokes the specified method with a GadgetInfo
  465.        derived from the 'Window' and 'Requester' pointers.  The GadgetInfo
  466.        is passed as the second parameter of the message, except for
  467.        OM_NEW, OM_SET, OM_NOTIFY, and OM_UPDATE, where the GadgetInfo
  468.        is passed as the third parameter.
  469.  
  470.        Implementers of new gadget methods should ensure that the
  471.        GadgetInfo is the second long-word of their message!
  472.  
  473.    SEE ALSO
  474.        NewObject(), DisposeObject(), GetAttr(), MakeClass(),
  475.        Document "Basic Object-Oriented Programming System for Intuition"
  476.        and the "boopsi Class Reference" document.
  477. reaction.lib/OpenLayoutWindowTagList     reaction.lib/OpenLayoutWindowTagList
  478.  
  479.    NAME
  480.        OpenLayoutWindowTagList -- Open a window at a suitable size for layout
  481.        OpenLayoutWindowTags -- Varags stub for OpenLayoutWindowTagList
  482.  
  483.    SYNOPSIS
  484.        window = OpenLayoutWindowTagList( layout, screen, taglist )
  485.  
  486.        struct Window *OpenLayoutWindowTagList( struct Gadget *,
  487.                struct Screen *, struct TagList * )
  488.  
  489.        window = OpenLayoutWindowTags( layout, screen, tag, ... )
  490.  
  491.        struct Window *OpenLayoutWindowTags( struct Gadget *,
  492.                struct Screen *, Tag, ... )
  493.  
  494.    FUNCTION
  495.        Determines the minimum size that will fit a layout and opens the window
  496.        at that size. The sizing limits of the window will be set according to
  497.        the layout's limits, and the layout will be added to the window,
  498.        making it relative to window size. The layout will fit the whole inner
  499.        size of the window. It will not be rendered, so you must call
  500.        RefreshGadgets(), possibly after adding your border gadgets.
  501.  
  502.        This function will set InnerWidth, InnerHeight, and the screen for the
  503.        window. Other tags you have to pass yourself.
  504.  
  505.    INPUTS
  506.        layout -- the layout hierarcy for the window
  507.        screen -- pointer to the screen the window will be opened on
  508.        taglist -- the additional tags for the window.
  509.  
  510.    RESULTS
  511.        A pointer to the opened window or NULL if the open failed.
  512. reaction.lib/RadioButtonsA                         reaction.lib/RadioButtonsA
  513.  
  514.    NAME
  515.        RadioButtonsA -- Make a linked list of radiobuttons
  516.        RadioButtons -- varags stub for RadioButtonsA
  517.  
  518.    SYNOPSIS
  519.        list = RadioButtonsA( array )
  520.        list = RadioButtons( label, ... )
  521.        struct List *RadioButtonsA( STRPTR * )
  522.        struct List *RadioButtons( STRPTR, ... )
  523.  
  524.    FUNCTION
  525.        Make a linked list of radiobutton nodes from the NULL terminated
  526.        label array. The labels are not copied, so they must stay
  527.        valid until the list is free'd.
  528.  
  529.    INPUTS
  530.        array -- a NULL terminated array of string pointers.
  531.  
  532.    RESULTS
  533.        list -- a linked list of radiobutton nodes
  534.